home *** CD-ROM | disk | FTP | other *** search
/ CD Exchange / CD Exchange - Volume 1.iso / utils / misc / machv / programmer.lha / docs / mach.doc next >
Encoding:
Text File  |  1993-12-20  |  16.4 KB  |  558 lines
  1. TABLE OF CONTENTS
  2.  
  3. mach.library/AllocMacroObject
  4. mach.library/atox
  5. mach.library/CloseListWindow
  6. mach.library/DeallocMacroObject
  7. mach.library/FindByName
  8. mach.library/FindConfigByName
  9. mach.library/FindMacroObject
  10. mach.library/FindUnderscoreChar
  11. mach.library/FreeMacroObject
  12. mach.library/FreeTempMacroBuffer
  13. mach.library/GetMacroObject
  14. mach.library/InitMacroObject
  15. mach.library/NewMacroObject
  16. mach.library/OpenListWindow
  17. mach.library/SortExecList
  18.  
  19. mach.library/AllocMacroObject                   mach.library/AllocMacroObject
  20.  
  21.     NAME
  22.     AllocMacroObject -- Allocate a MacroObject.
  23.    
  24.     SYNOPSIS
  25.     AllocMacroObject(void)
  26.    
  27.     struct MacroObject* AllocMacroObject( )
  28.    
  29.     FUNCTION
  30.     Allocate memory for a MacroObject. This does nothing more than that.
  31.     Do not use static MacroObjects because the struct size may change in
  32.     the future.
  33.  
  34.     WARNING
  35.    
  36.     INPUTS
  37.     None
  38.    
  39.     RESULTS
  40.     Pointer to a MacroObject if successful,
  41.     NULL if not and low memory alert put up.
  42.    
  43.     SEE ALSO
  44.     DeallocMacroObject
  45. mach.library/atox                                           mach.library/atox
  46.  
  47.     NAME
  48.     atox -- Ascii hex to long.
  49.    
  50.     SYNOPSIS
  51.     atox(char *)
  52.    
  53.     long atox(char *string )
  54.    
  55.     FUNCTION
  56.     Convert an ascii string of hex characters to a long integer.
  57.  
  58.     INPUTS
  59.     string - Pointer to ascii string.
  60.    
  61.     RESULTS
  62.     Long integer.
  63.    
  64.     SEE ALSO
  65. mach.library/CloseListWindow                     mach.library/CloseListWindow
  66.  
  67.     NAME
  68.     CloseListWindow -- Close the list window.
  69.    
  70.     SYNOPSIS
  71.     CloseListWindow(void)
  72.    
  73.     void CloseListWindow(void)
  74.    
  75.     FUNCTION
  76.     Closes the list window. 
  77.  
  78.     INPUTS
  79.     None.
  80.  
  81.     RESULTS
  82.     The window is closed.
  83.  
  84.     SEE ALSO
  85.     OpenListWindow
  86. mach.library/DeallocMacroObject                mach.library/DellocMacroObject
  87.  
  88.     NAME
  89.     DeallocMacroObject -- Deallocate a MacroObject.
  90.    
  91.     SYNOPSIS
  92.     DeallocMacroObject(struct MacroObject* mo)
  93.    
  94.     void DeallocMacroObject(struct MacroObject* )
  95.    
  96.     FUNCTION
  97.     Deallocate memory for a MacroObject. This does nothing more than that.
  98.     Do not use static MacroObjects because the struct size may change in
  99.     the future.
  100.  
  101.     WARNING
  102.    
  103.     INPUTS
  104.     mo - a pointer to a MacroObject. NULL is ok.
  105.    
  106.     RESULTS
  107.     The MacroObject is freed.
  108.    
  109.     SEE ALSO
  110.     AllocMacroObject
  111. mach.library/FindByName                               mach.library/FindByName
  112.    
  113.     NAME
  114.     FindByName -- Find a MacroObject by its name.
  115.    
  116.     SYNOPSIS
  117.     FindByName(cfg, sname, match_type )
  118.                A0   A1     D0
  119.    
  120.     struct MacroObject* FindByName(struct MachCfg *, char *, UWORD , UWORD )
  121.    
  122.     FUNCTION
  123.     Finds a MacroObject by its name. May expand or restrict search with 
  124.     different values for match_type. 
  125.    
  126.     WARNING
  127.     Be sure to surround calls to this function with Obtain/ReleaseSemaphore 
  128.    
  129.     INPUTS
  130.     cfg            = pointer to the desired configuration.
  131.     sname        = pointer to macro name.
  132.     match_type    = control the search with these flags or'ed together:
  133.  
  134.        MT_LOCALS        - search only the supplied configuration.
  135.        MT_GLOBALS       - search the supplied configuration and then
  136.                           the first configuration if not the same.
  137.        MT_WILDCARDS     - allow wild cards in the search.  
  138.        MT_EXACT_MATCH   - macro name must match exactly.
  139.        MT_SLOPPY_MATCH  - case insensitive and match only up to length of
  140.                           supplied name.
  141.        MT_MATCH_NEXT    - continue to search after match with wildcards.
  142.  
  143.     RESULT
  144.     results - pointer to found MacroObject if successful,
  145.                NULL if not.
  146.    
  147.     EXAMPLE
  148.     #include <stdio.h>                                                       
  149.     #include <ctype.h>                                                       
  150.     #include <exec/types.h>
  151.     #include <exec/libraries.h>
  152.     #include <proto/exec.h>                                                  
  153.     #include "mach.h"
  154.     #include "machlib.h"                                            
  155.     #include "machlib_protos.h"                                     
  156.     #include "machlib_pragmas.h"                                    
  157.                                                                              
  158.     void FindMacro(char *mname);                                             
  159.                                                                              
  160.     struct MachLibrary *MachBase;                                            
  161.                                                                              
  162.     main(int argc, char **argv)                                              
  163.     {                                                                        
  164.         if (argc == 2) {                                                     
  165.             MachBase = (struct MachLibrary*)OpenLibrary("mach.library",37L); 
  166.             if (MachBase) {                                                  
  167.                 FindMacro(argv[1]);                                          
  168.                 CloseLibrary((struct Library*)MachBase);                     
  169.             }                                                                
  170.         }                                                                    
  171.     }                                                                        
  172.                                                                              
  173.     void FindMacro(char *mname)                                              
  174.     {                                                                        
  175.         ULONG mt;                                                            
  176.         struct MacroObject *mo;                                              
  177.                                                                              
  178.         ObtainSemaphore(&MachBase->ml_BaseSemaphore);                        
  179.         mt = MT_WILDCARDS | MT_GLOBALS;                                      
  180.         while (mo = FindByName(MachBase->ml_CurConfig,mname,mt)) {           
  181.             printf("found %s\n", mo->mo_Name);                               
  182.             mt |= MT_MATCH_NEXT;
  183.         }                                                                    
  184.         ReleaseSemaphore(&MachBase->ml_BaseSemaphore);                       
  185.     }
  186.  
  187.     SEE ALSO
  188.    
  189. mach.library/FindConfigByName                   mach.library/FindConfigByName
  190.  
  191.     NAME
  192.     FindConfigByName -- Find a configuration by name.
  193.    
  194.     SYNOPSIS
  195.     FindConfigByName(cname)
  196.                      A0
  197.  
  198.     struct MachCfg* FindConfigByName(char *)
  199.    
  200.     FUNCTION
  201.     Finds the configuration by matching titles with cname.
  202.     Uses stpicmp() for case insensitive matching upto length of cname.
  203.    
  204.     INPUTS
  205.     cname - pointer to a configuration name.
  206.    
  207.     RESULTS
  208.     Pointer to found configuration if successful,
  209.     NULL if not.
  210.    
  211.     SEE ALSO
  212.    
  213. mach.library/FindMacroObject                     mach.library/FindMacroObject
  214.  
  215.     NAME
  216.     FindMacroObject -- Find an existing MacroObject.
  217.    
  218.     SYNOPSIS
  219.     FindMacroObject(cfg, code, qual,match_type)
  220.                        A0     D0    D1    D2
  221.    
  222.     struct MacroObject* FindMacroObject(struct MachCfg *,
  223.     UWORD ,UWORD ,ULONG)
  224.    
  225.     FUNCTION
  226.     Find a MacroObject in chain at code that matches qual.
  227.     Searches global macros if match_type == MT_GLOBALS.
  228.    
  229.     INPUTS
  230.     cfg        - a pointer to the desired configuration.
  231.     code     - keycode or UNKEYED for a un-keyed named macro.
  232.     qual    - qualifiers for hotkey combination. -1 for UNKEYED.
  233.     match_type - MT_GLOBALS to seach THE specified configuration and 
  234.                  then the first for globals. Use MT_LOCALS to search 
  235.                  just the specified configuration.
  236.    
  237.     RESULTS
  238.     Pointer to old MacroObject if successful,
  239.     NULL if not.
  240.    
  241.     SEE ALSO
  242.     NewMacroObject, GetMacroObject
  243. mach.library/FindUnderscoreChar               mach.library/FindUnderscoreChar
  244.  
  245.     NAME
  246.     FindUnderscoreChar -- Find keycode for underscored character.
  247.  
  248.     SYNOPSIS
  249.     FindUnderscoreChar(char *)
  250.    
  251.     UBYTE FindUnderscoreChar(char *s )
  252.    
  253.     FUNCTION
  254.     Searches ascii string for underscore character. When found, returns
  255.     keycode for the following character. Given the string '_Cancel', this
  256.     function returns the keycode for the letter 'C' using the current 
  257.     keymap. 
  258.  
  259.     This is usually used to find the keycode for a keyboard shortcut for
  260.     a gadtools gadget.
  261.  
  262.     INPUTS
  263.     s - Pointer to ascii string. 
  264.    
  265.     RESULTS
  266.     Keycode for character following underscore.
  267.    
  268.     SEE ALSO
  269. mach.library/FreeMacroObject                     mach.library/FreeMacroObject
  270.  
  271.     NAME
  272.     FreeMacroObject -- Find and free a MacroObject.
  273.    
  274.     SYNOPSIS
  275.     FreeMacroObject(cfg, code, qual)
  276.                     A0   D0    D1
  277.    
  278.     void FreeMacroObject(struct MachCfg *, char *, UWORD ,UWORD )
  279.    
  280.     FUNCTION
  281.     Find and then free a MacroObject and its macro.
  282.     Remove from configuration macro list.
  283.    
  284.     INPUTS
  285.     cfg     - a pointer to the desired configuration.
  286.     code - keycode or UNKEYED for a un-keyed named macro.
  287.     qual - qualifiers for hotkey combination. Ordinal number for UNKEYED 
  288.            macro.
  289.    
  290.     RESULTS
  291.     None.
  292.    
  293.     SEE ALSO
  294.  
  295. mach.library/FreeTempMacroBuffer             mach.library/FreeTempMacroBuffer
  296.  
  297.     NAME
  298.     FreeTempMacroBuffer -- Frees MachBase->ml_TempMacroBuffer.
  299.  
  300.     SYNOPSIS
  301.     FreeTempMacroBuffer(void)
  302.  
  303.     void FreeTempMacroBuffer(void)
  304.  
  305.     FUNCTION
  306.     Free the buffer MachBase->ml_TempMacroBuffer. This is the buffer
  307.     used when recording a macro. Its size is taken from
  308.     MachBase->ml_CurConfig->mc_Buffersize.
  309.  
  310.     INPUTS
  311.     None.
  312.  
  313.     RESULTS
  314.     MachBase->ml_TempMacroBuffer is freed and nulled.
  315.  
  316.     SEE ALSO
  317.    
  318. mach.library/GetMacroObject                       mach.library/GetMacroObject
  319.  
  320.     NAME
  321.     GetMacroObject -- Find an old or insert new MacroObject.
  322.    
  323.     SYNOPSIS
  324.     GetMacroObject(cfg, code, qual)
  325.                    A0   D0    D1
  326.  
  327.     struct MacroObject* GetMacroObject(struct MachCfg *,
  328.     UWORD ,UWORD ,ULONG)
  329.    
  330.     FUNCTION
  331.     Find a MacroObject matching code/qual. If not found, allocate
  332.     new MacroObject and add it to the hotkey list in the specified
  333.     configuration.
  334.     mo_Link.ln_Name will point to mo_Name.
  335.    
  336.     WARNING
  337.     This function returns an existing MacroObject if code and qual match.
  338.    
  339.     INPUTS
  340.     cfg        - a pointer to the desired configuration.
  341.     code     - keycode or UNKEYED for a un-keyed named macro.
  342.     qual    - qualifiers for hotkey combination. -1 for UNKEYED.
  343.     match_type - MT_GLOBALS to seach THE specified configuration and 
  344.                  then the first for globals. Use MT_LOCALS to search 
  345.                  just the specified configuration.
  346.  
  347.     RESULTS
  348.     Pointer to old or new MacroObject if successful,
  349.     NULL if not and low memory requester put up.
  350.     mo_Code and mo_Qual are set.
  351.     mo_Link.ln_Name will point to mo_Name.
  352.    
  353.     SEE ALSO
  354.     NewMacroObject
  355. mach.library/InitMacroObject                     mach.library/InitMacroObject
  356.  
  357.     NAME
  358.     InitMacroObject -- Initialize a MacroObject.
  359.    
  360.     SYNOPSIS
  361.     InitMacroObject(mo)
  362.                     A0
  363.  
  364.     struct MacroObject* InitMacroObject(struct MacroObject *)
  365.  
  366.     FUNCTION
  367.     Initialize (zeroes) a MacroObject. Does not affect linkage
  368.     pointers. Frees a macro if mo_Macro is not NULL.
  369.    
  370.     WARNING
  371.    
  372.     INPUTS
  373.     mo - a pointer to a MacroObject
  374.    
  375.     RESULTS
  376.     results - a pointer to the initialized MacroObject.
  377.    
  378.     SEE ALSO
  379.  
  380. mach.library/NewMacroObject                       mach.library/NewMacroObject
  381.  
  382.     NAME
  383.     NewMacroObject -- Alloc and connect a new (or old) MacroObject.
  384.    
  385.     SYNOPSIS
  386.     NewMacroObject(cfg, string, code, qual)
  387.                    A0   A1      D0    D1
  388.    
  389.     struct MacroObject* NewMacroObject(struct MachCfg *, char *,
  390.     UWORD ,UWORD )
  391.    
  392.     FUNCTION
  393.     Allocate a new MacroObject and add it to the hotkey list in the
  394.     specified configuration. Space is allocated for the string and
  395.     it is copied to mo_Macro. mo_Size, mo_Code and mo_Qual are set.
  396.     mo_Link.ln_Name will point to mo_Name.
  397.    
  398.     WARNING
  399.     This function uses an existing MacroObject if code and qual match.
  400.     It will discard existing macro and replace it with string.
  401.    
  402.     INPUTS
  403.     cfg        - a pointer to the desired configuration.
  404.     string    - pointer to a null terminated text string.
  405.     code     - keycode or UNKEYED for a un-keyed named macro.
  406.     qual    - qualifiers for hotkey combination. -1 for UNKEYED.
  407.    
  408.     RESULTS
  409.     results - pointer to new MacroObject if successful,
  410.               NULL if not and low memory alert put up.
  411.    
  412.     SEE ALSO
  413.     GetMacroObject
  414. mach.library/OpenListWindow                       mach.library/OpenListWindow
  415.  
  416.     NAME
  417.     OpenListWindow -- Open a window listing macros or configurations.
  418.    
  419.     SYNOPSIS
  420.     OpenListWindow(tags)
  421.                    A0
  422.    
  423.     BOOL OpenListWindow(struct TagItem *tags)
  424.    
  425.     FUNCTION
  426.     This opens a window with a list gadget containing macro names, alarm 
  427.     names, window or screen titles, or configuration titles. When called, 
  428.     a separate process is created which waits on the window signals.
  429.     When the user makes a selection, your task will be signaled and 
  430.     MachBase->ml_ListSelection will point to the string. If the user made 
  431.     no selection (clicked on Cancel, the close gadget or pressed Return with 
  432.     the string gadget empty), MachBase->ml_ListSelection will be NULL.
  433.  
  434.     Current tags:
  435.  
  436.     LIST_TaskInfo      Pointer to a TaskInfo struct (see mach.h).
  437.     LIST_Type          See below for types.
  438.     LIST_LeftEdge      Default = -1 which centers the window.
  439.     LIST_TopEdge       Default = -1 which places it at 10 below screen top.
  440.     LIST_Globals       Current configuration + globals? Default = TRUE.
  441.     LIST_AlarmsOnly    List only alarms. Default = FALSE.
  442.     LIST_Title         List window title.
  443.     LIST_OkayString    Okay gadget text.
  444.     LIST_CancelString  Cancel gadget text.
  445.  
  446.     Allowable tag values for LIST_Type:
  447.  
  448.     LIST_WINDOWS        List window titles.
  449.     LIST_SCREENS        List screen titles.
  450.     LIST_MACRONAMES        List macro names.
  451.     LIST_MACROALARMS    List macros with clk_alarm.
  452.     LIST_CONFIGNAMES    List configuration names.
  453.     LIST_WIN_SCR_PRG    List windows, screens, program names. (37.5)
  454.                         Program names are names of programs that have a
  455.                         window open.
  456.  
  457.     WARNING
  458.     This routine is not reentrant! Only one list window may be open at a
  459.     time.
  460.     The window will open on the front screen, public or not. If the screen
  461.     closes with the list still open, the system will crash. However, MachV
  462.     monitors screen closings and will close it for you. MachV will also
  463.     close it when MachV is terminated. You will receive your signal if the 
  464.     list window is being closed for you.
  465.  
  466.     INPUTS
  467.     tags - tags describing desired attributes.
  468.    
  469.     RESULTS
  470.     TRUE if opened successfully or is already open.
  471.     FALSE if not.
  472.    
  473.     EXAMPLE
  474.     #include <stdio.h>                                                       
  475.     #include <ctype.h>                                                       
  476.     #include <exec/types.h>
  477.     #include <exec/libraries.h>
  478.     #include <proto/exec.h>                                                  
  479.     #include "mach.h"
  480.     #include "machlib.h"                                            
  481.     #include "machlib_protos.h"                                     
  482.     #include "machlib_pragmas.h"                                    
  483.  
  484.     struct MachLibrary *MachBase;                                            
  485.  
  486.     /* This lets you call OpenListWindow() with a variable number of tags. */
  487.  
  488.     BOOL OpenListWindowTags(ULONG tags,...);
  489.  
  490.     BOOL OpenListWindowTags(ULONG tags,...)
  491.     {
  492.         return(OpenListWindow((struct TagItem *)&tags));
  493.     }
  494.  
  495.     main(int argc, char **argv)                                              
  496.     {                                                                        
  497.         struct TaskInfo list_task_info;
  498.         LONG listsig_nr;
  499.         ULONG list_sig;
  500.  
  501.         MachBase = (struct MachLibrary*)OpenLibrary("mach.library",37L); 
  502.         if (MachBase) {                                                  
  503.             if ((listsig_nr = AllocSignal(-1L)) != -1L) {
  504.                 list_sig = 1 << listsig_nr;
  505.                 list_task_info.Task = FindTask(NULL);
  506.                 list_task_info.Sig = list_sig;
  507.     
  508.                 /* Open list window listing macro names */
  509.     
  510.                 if (OpenListWindowTags(LIST_TaskInfo,    (ULONG)&list_task_info,
  511.                                        LIST_Type,        LIST_MACRONAMES,
  512.                                        LIST_Title,        (ULONG)"Macro Names",
  513.                                        TAG_DONE)) {
  514.     
  515.                     /* Wait for selection, ok, cancel or close window */
  516.     
  517.                     Wait(list_sig);
  518.     
  519.                     FreeSignal(listsig_nr);
  520.  
  521.                     if (MachBase->ml_ListSelection ) 
  522.                         printf("Selected %s\n",MachBase->ml_ListSelection);
  523.                     else
  524.                         printf("No selection\n" );
  525.                 }
  526.             }
  527.             CloseLibrary((struct Library*)MachBase);                     
  528.         }                                                                
  529.     }                                                                        
  530.                                                                              
  531.     SEE ALSO
  532.     DeallocMacroObject
  533. mach.library/SortExecList                           mach.library/SortExecList
  534.  
  535.     NAME
  536.     SortExecList -- Sort an exec list.
  537.    
  538.     SYNOPSIS
  539.     SortExecList(struct List *)
  540.    
  541.     void SortExecList(struct List *list)
  542.    
  543.     FUNCTION
  544.     Sorts an exec list based on ln_Name. Uses Stricmp() for a case insensitive 
  545.     sort.
  546.  
  547.     WARNING
  548.     No arbitration is performed. The user should ensure that the list is
  549.     protected from access by other tasks by using semaphores or Forbid().
  550.  
  551.     INPUTS
  552.     list - Pointer to an exec list.
  553.  
  554.     RESULTS
  555.     The list is sorted.
  556.  
  557.     SEE ALSO
  558.